fix: require explicit refresh for bundle manifest changes - #4477

Thanks — this correctly fixes the primary #4434 failure (a version-changing normal install advancing the record past stale components), with a clean guard and regression test, and the disclosure is appreciated. One thing before merge: #4434 reported a second case that this doesn't cover — components installed individually before the bundle, where every primitive is classified "already present" so the new bundle record ends up with no contributed-component entries. As written, Closes #4434 would auto-close the issue while that half remains. Please either extend this to handle the individually-installed case (with a test), or change Closes #4434 to Refs #4434 and I'll keep the issue open for a follow-up. Also heads-up: #4466–#4470 ([@marcelsafin](https://github.com/marcelsafin)) touch the same installer.py version-integrity path — worth confirming no overlap. I'll trigger the automated review in parallel.

The automated review surfaced a bigger issue than my earlier note: rejecting a version-changing bundle install and pointing users to bundle update breaks the exact case #4434 was reported for — local bundles. bundle update only resolves catalog bundles; it can't update a local/path-installed bundle (_local_manifest_source), and the original repro was bundle install <local bundle.yml> --offline. So as written, local-bundle users go from "silent stale record" to "no upgrade path at all," which is worse for them.

Please make the local-bundle case work end to end — either extend bundle update to accept a local path/manifest, or have the version-change guard perform the refresh for local bundles rather than just rejecting. And (from before) confirm whether #4434's second case is in scope — individually-installed components producing a record with no contributed-component entries; if not, change Closes #4434 to Refs #4434 so the issue stays open. Re-request once addressed.

Thanks — --refresh for local sources is exactly the right fix; the per-source-type error message pointing to bundle update <id> vs install <path> --refresh resolves the dead-end cleanly. (My 17:16 comment crossed with your 15:00 commit — you'd already addressed it.) Re-requesting review/CI on 3b6d00c5; given it touches the bundler, I want the macOS/Windows matrix green before merging. One thing still open: does this cover #4434's second case — components installed individually before the bundle producing a record with no contributed-component entries? If not, let's change Closes #4434 to Refs #4434 and track that separately.

The --refresh addition resolves the local dead-end well. One more edge from the re-review: the offline refresh route (bundle install <path> --refresh --offline) fails for owned components that require catalog resolution — DefaultPrimitiveInstaller(allow_network=False) routes refresh through managers that still need the catalog. Since offline/local is exactly #4434's motivating case, this should work end-to-end (or fail with a clear "this component needs network to refresh" message rather than a confusing error). Re-request once handled.

Posted on behalf of @rksharma-owg by OpenAI Codex (GPT-6 Astra, autonomous).

Updated in 2fd5c88: local-source refresh documentation now separates the manifest from catalog-backed component payloads. Offline errors identify the component and direct users to retry without --offline; they no longer suggest pre-installing an already-owned component. Three new CLI cases exercise manifest, directory, and ZIP sources through the real extension installer, with only catalog I/O substituted by local artifacts. They verify unchanged payload/record on offline failure and successful version refresh on retry.

All 115 focused tests and Ruff passed. The PR continues to use Refs #4434; the independently-installed-component ownership case remains a separate follow-up. The fixes are pushed, but GitHub rejected my review re-request because this account lacks RequestReviewsByLogin permission; a maintainer needs to trigger re-review/CI.

Posted on behalf of @rksharma-owg by OpenAI Codex (autonomous).

Updated in 1d18074. Normal installs now compare the recorded owned components with the requested plan before any primitive operation, rejecting metadata changes and removals even when the bundle version is unchanged. Unchanged entries, reordering, and additions remain supported; --refresh applies the revised manifest through the existing refresh/removal path.

Seventeen regression cases failed on the previous head and pass now. All 343 bundle tests pass, including real extension-installer coverage for manifest, directory, and ZIP sources with an unchanged bundle version. Ruff and the documentation lint check also pass. The full repository suite was not repeated; its earlier local limitations remain documented in the PR body.

The existing review request to @mnriem is still pending. Fresh CI runs report action_required with no jobs started; this fork update needs maintainer approval to run CI. This account has read access only. Python CI: https://github.com/github/spec-kit/actions/runs/34484464779. #4434's independently-installed-component case remains outside this PR.

Thanks @rksharma-owg — the same-version component-pin guard (issubset on the recorded components) closes the L106 case, and the offline refresh path now preserves payload/manifest/record with a clear retry message. That covers both the automated finding and my earlier offline note. This is on me next: I'll trigger CI on the new head and do a full read of the record/rollback logic. One heads-up — this overlaps #4470 in install_bundle, so depending on merge order one of the two will need a rebase; I'll sequence them.